---
title: 인증
description: Astro 인증 소개
i18nReady: true
---

import { Steps } from '@astrojs/starlight/components'
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import UIFrameworkTabs from '~/components/tabs/UIFrameworkTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

인증 및 승인은 웹사이트 또는 앱에 대한 액세스를 관리하는 두 가지 보안 프로세스입니다. 인증은 방문자의 신원을 확인하는 반면, 승인은 보호 구역 및 자원에 대한 접근 권한을 부여합니다.

인증을 사용하면 사이트의 특정 영역을 로그인한 개인에 맞춰 사용자 정의할 수 있으며 개인 정보 또는 비공개 정보를 최대한 보호할 수 있습니다. 인증 라이브러리 (예: [Better Auth](https://better-auth.com/), [Clerk](https://clerk.com))는 이메일 로그인 및 OAuth 공급자와 같은 다양한 인증 방법을 위한 유틸리티를 제공합니다.

:::tip
Astro에 대한 공식 인증 솔루션은 없지만 통합 디렉터리에서 [커뮤니티 "인증" 통합](https://astro.build/integrations/?search=auth)을 찾을 수 있습니다.
:::

<ReadMore>이러한 백엔드 서비스에 대한 전용 가이드에서 [Supabase로 인증을 추가](/ko/guides/backend/supabase/#supabase로-인증-추가)하거나 [Firebase로 인증을 추가](/ko/guides/backend/firebase/#firebase로-인증-추가)하는 방법을 알아보세요.</ReadMore>

## Better Auth

Better Auth는 프레임워크에 구애받지 않는 TypeScript용 인증 (및 권한 부여) 프레임워크입니다. 기본적으로 포괄적인 기능 세트를 제공하며 고급 기능을 간편하게 추가할 수 있는 플러그인 생태계가 포함되어 있습니다.

Astro를 즉시 지원하며, 이를 사용하여 Astro 프로젝트에 인증을 추가할 수 있습니다.

### 설치

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install better-auth
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add better-auth
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add better-auth
  ```
  </Fragment>
</PackageManagerTabs>

자세한 설정 지침은 [Better Auth 설치 가이드](https://www.better-auth.com/docs/installation)를 참조하세요.

### 구성

[Better Auth 설치 가이드](https://www.better-auth.com/docs/installation#configure-database)에 설명된 대로 사용자 데이터와 선호하는 인증 방법을 저장하도록 데이터베이스 테이블을 구성합니다. 그런 다음 Astro 프로젝트에 Better Auth 핸들러를 마운트해야 합니다.

```ts title="src/pages/api/auth/[...all].ts"
import { auth } from "../../../lib/auth"; // Better Auth 인스턴스를 가져옵니다.
import type { APIRoute } from "astro";

export const prerender = false; // 'server' 모드에서는 필요하지 않습니다.

export const ALL: APIRoute = async (ctx) => {
	return auth.handler(ctx.request);
};
```

자세한 내용은 [Better Auth Astro 가이드](https://www.better-auth.com/docs/integrations/astro)를 참조하세요.


### 사용

Better Auth는 Vanilla JS, React, Vue, Svelte, Solid를 포함한 다양한 프레임워크를 위한 `createAuthClient` 헬퍼를 제공합니다. 

예를 들어, React용 클라이언트를 생성하려면 `better-auth/react`에서 헬퍼를 가져옵니다:


<UIFrameworkTabs>
  <Fragment slot="react">
   ```ts title="src/lib/auth-client.ts"
  import { createAuthClient } from 'better-auth/react';

  export const authClient = createAuthClient();

  export const { signIn, signOut } = authClient;
  ```
  </Fragment>
  <Fragment slot="solid">
  ```ts title="src/lib/auth-client.ts"
  import { createAuthClient } from 'better-auth/solid';

  export const authClient = createAuthClient();

  export const { signIn, signOut } = authClient;
  ```
  </Fragment>
  <Fragment slot="svelte">
   ```ts title="src/lib/auth-client.ts"
  import { createAuthClient } from 'better-auth/svelte';

  export const authClient = createAuthClient();

  export const { signIn, signOut } = authClient;
  ```
  </Fragment>
  <Fragment slot="vue">
  ```ts title="src/lib/auth-client.ts"
  import { createAuthClient } from 'better-auth/vue';

  export const authClient = createAuthClient();

  export const { signIn, signOut } = authClient;
  ```
  </Fragment>
</UIFrameworkTabs>

클라이언트가 설정되면 이를 사용하여 Astro 컴포넌트 또는 프레임워크별 파일에서 사용자를 인증할 수 있습니다. 다음 예시에서는 구성된 `signIn()` 및 `signOut()` 함수를 사용하여 로그인 또는 로그아웃 기능을 추가합니다.


```astro title="src/pages/index.astro"
---
import Layout from 'src/layouts/Base.astro';
---
<Layout>
  <button id="login">Login</button>
  <button id="logout">Logout</button>

  <script>
    const { signIn, signOut } = await import("./lib/auth-client")
    document.querySelector("#login").onclick = () => signIn.social({
      provider: "github",
      callbackURL: "/dashboard",
    })
    document.querySelector("#logout").onclick = () => signOut()
  </script>
</Layout>
```

그런 다음 `auth` 객체를 사용하여 서버 측 코드에서 사용자의 세션 데이터를 가져올 수 있습니다. 다음 예시는 인증된 사용자의 이름을 표시하여 페이지 콘텐츠를 개인화합니다:

```astro title="src/pages/index.astro"
---
import { auth } from "../../../lib/auth"; // Better Auth 인스턴스를 가져옵니다.

export const prerender = false; // 'server' 모드에서는 필요하지 않습니다.

const session = await auth.api.getSession({
	headers: Astro.request.headers,
});
---

<p>{session.user?.name}</p>
```

미들웨어와 `auth` 객체를 사용하여 경로를 보호할 수도 있습니다. 다음 예시는 로그인한 대시보드 경로에 액세스하려는 사용자가 인증되었는지 확인하고 인증되지 않은 경우 홈 페이지로 리디렉션합니다.

```ts title="src/middleware.ts"
import { auth } from "../../../auth"; // Better Auth 인스턴스를 가져옵니다.
import { defineMiddleware } from "astro:middleware";
 
export const onRequest = defineMiddleware(async (context, next) => {
	const isAuthed = await auth.api
		.getSession({
			headers: context.request.headers,
		})
	if (context.url.pathname === "/dashboard" && !isAuthed) {
		return context.redirect("/");
	}
	return next();
});
```

### 다음 단계

- [Better Auth + Astro 가이드](https://www.better-auth.com/docs/integrations/astro)
- [Better Auth + Astro 예시](https://github.com/better-auth/examples/tree/main/astro-example)
- [Better Auth 문서](https://www.better-auth.com/docs)
- [Better Auth GitHub 리포지토리](https://github.com/better-auth/better-auth)

## Clerk

Clerk는 임베드 가능한 UI, 유연한 API, 관리자 대시보드로 구성된 완벽한 제품군으로 사용자를 인증하고 관리할 수 있습니다. [Astro용 공식 Clerk SDK](https://clerk.com/docs/references/astro/overview)를 사용할 수 있습니다.

### 설치

원하는 패키지 관리자를 사용하여 `@clerk/astro`를 설치합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @clerk/astro
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @clerk/astro
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @clerk/astro
  ```
  </Fragment>
</PackageManagerTabs>

### 구성

[Clerk의 자체 Astro 빠른 시작 가이드](https://clerk.com/docs/quickstarts/astro)를 따라 Astro 프로젝트에서 Clerk 통합 및 미들웨어를 설정하세요.

### 사용

Clerk는 사용자의 인증 상태에 따라 페이지의 표시 여부를 제어할 수 있는 컴포넌트를 제공합니다. 로그아웃한 사용자에게는 로그인한 사용자에게 제공되는 콘텐츠 대신 로그인 버튼을 표시합니다:

```astro title="src/pages/index.astro"
---
import Layout from 'src/layouts/Base.astro';
import { SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/astro/components';

export const prerender = false; // 'server' 모드에서는 필요하지 않습니다.
---
<Layout>
    <SignedIn>
        <UserButton />
    </SignedIn>
    <SignedOut>
        <SignInButton />
    </SignedOut>
</Layout>
```

또한 Clerk를 사용하면 미들웨어를 통해 서버에서 경로를 보호할 수 있습니다. 보호할 경로를 지정하고 인증되지 않은 사용자에게 로그인하라는 메시지를 표시할 수 있습니다:

```ts title="src/middleware.ts"
import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server';

const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/forum(.*)',
]);

export const onRequest = clerkMiddleware((auth, context) => {
  if (!auth().userId && isProtectedRoute(context.request)) {
    return auth().redirectToSignIn();
  }
});
```

### 다음 단계

- [공식 `@clerk/astro` 문서](https://clerk.com/docs/references/astro/overview)를 읽어보세요.
- [Clerk + Astro 빠른 시작 프로젝트](https://github.com/clerk/clerk-astro-quickstart) 템플릿으로 시작하세요.

## Lucia

[Lucia](https://lucia-auth.com/)는 Astro를 비롯한 여러 프레임워크에서 세션 기반 인증을 구현하기 위한 리소스입니다.

### 가이드

<Steps>

1. 선택한 데이터베이스로 [기본 세션 API](https://lucia-auth.com/sessions/basic-api/)를 생성합니다.
2. 엔드포인트와 미들웨어를 사용하여 [세션 쿠키](https://lucia-auth.com/sessions/cookies/astro)를 추가합니다.
3. 구현한 API를 사용하여 [GitHub OAuth](https://lucia-auth.com/tutorials/github-oauth/astro)를 구현합니다.

</Steps>

### 예시

- [Astro에서 GitHub OAuth를 구현하는 예시](https://github.com/lucia-auth/example-astro-github-oauth)
- [Astro에서 Google OAuth를 구현하는 예시](https://github.com/lucia-auth/example-astro-google-oauth)
- [Astro에서 2FA를 사용하여 이메일 및 비밀번호를 구현하는 예시 example](https://github.com/lucia-auth/example-astro-email-password-2fa)
- [Astro에서 2FA와 WebAuthn를 사용하여 이메일 및 비밀번호를 구현하는 예시](https://github.com/lucia-auth/example-astro-email-password-webauthn)

## 커뮤니티 자료

- [Astro 및 Azure Static Web App에서 Microsoft Entra Id EasyAuth 사용](https://agramont.net/blog/entra-id-easyauth-with-astro/)
